<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
<title>A Simple JavaServer Faces Application - The Java EE 5 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2008-10-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/j5eetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnafd.html">4.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnagx.html">5.&nbsp;&nbsp;JavaServer Pages Technology</a></p>
<p class="toc level2"><a href="bnajo.html">6.&nbsp;&nbsp;JavaServer Pages Documents</a></p>
<p class="toc level2"><a href="bnakc.html">7.&nbsp;&nbsp;JavaServer Pages Standard Tag Library</a></p>
<p class="toc level2"><a href="bnalj.html">8.&nbsp;&nbsp;Custom Tags in JSP Pages</a></p>
<p class="toc level2"><a href="bnaon.html">9.&nbsp;&nbsp;Scripting in JSP Pages</a></p>
<p class="toc level2"><a href="bnaph.html">10.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level3"><a href="gentextid-10866.html">JavaServer Faces Technology User Interface</a></p>
<p class="toc level3"><a href="bnapj.html">JavaServer Faces Technology Benefits</a></p>
<p class="toc level3"><a href="bnapk.html">What Is a JavaServer Faces Application?</a></p>
<div class="onpage">
<p class="toc level3"><a href="">A Simple JavaServer Faces Application</a></p>
<p class="toc level4"><a href="#bnapm">Steps in the Development Process</a></p>
<p class="toc level4"><a href="#bnapo">Mapping the <tt>FacesServlet</tt> Instance</a></p>
<p class="toc level4"><a href="#bnapp">Creating the Pages</a></p>
<p class="toc level5"><a href="#bnapq">Declaring the Tag Libraries</a></p>
<p class="toc level5"><a href="#bnapr">Adding the <tt>view</tt> and <tt>form</tt> Tags</a></p>
<p class="toc level5"><a href="#bnaps">Adding a Label Component</a></p>
<p class="toc level5"><a href="#bnapt">Adding an Image</a></p>
<p class="toc level5"><a href="#bnapu">Adding a Text Field</a></p>
<p class="toc level5"><a href="#bnapv">Registering a Validator on a Text Field</a></p>
<p class="toc level5"><a href="#bnapw">Adding a Custom Message</a></p>
<p class="toc level5"><a href="#bnapx">Adding a Button</a></p>
<p class="toc level5"><a href="#bnapy">Displaying Error Messages</a></p>
<p class="toc level4 tocsp"><a href="#bnapz">Defining Page Navigation</a></p>
<p class="toc level4"><a href="#bnaqa">Configuring Error Messages</a></p>
<p class="toc level4"><a href="#bnaqb">Developing the Beans</a></p>
<p class="toc level4"><a href="#bnaqc">Adding Managed Bean Declarations</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnaqd.html">User Interface Component Model</a></p>
<p class="toc level4"><a href="bnaqd.html#bnaqe">User Interface Component Classes</a></p>
<p class="toc level4"><a href="bnaqd.html#bnaqf">Component Rendering Model</a></p>
<p class="toc level4"><a href="bnaqd.html#bnaqi">Conversion Model</a></p>
<p class="toc level4"><a href="bnaqd.html#bnaqj">Event and Listener Model</a></p>
<p class="toc level4"><a href="bnaqd.html#bnaqk">Validation Model</a></p>
<p class="toc level3 tocsp"><a href="bnaql.html">Navigation Model</a></p>
<p class="toc level3"><a href="bnaqm.html">Backing Beans</a></p>
<p class="toc level4"><a href="bnaqm.html#bnaqn">Creating a Backing Bean Class</a></p>
<p class="toc level5"><a href="bnaqm.html#bnaqo">Configuring a Bean</a></p>
<p class="toc level5"><a href="bnaqm.html#bnaqp">Using the Unified EL to Reference Backing Beans</a></p>
<p class="toc level3 tocsp"><a href="bnaqq.html">The Life Cycle of a JavaServer Faces Page</a></p>
<p class="toc level4"><a href="bnaqq.html#bnaqs">Restore View Phase</a></p>
<p class="toc level5"><a href="bnaqq.html#bnaqt">Apply Request Values Phase</a></p>
<p class="toc level5"><a href="bnaqq.html#bnaqu">Process Validations Phase</a></p>
<p class="toc level5"><a href="bnaqq.html#bnaqv">Update Model Values Phase</a></p>
<p class="toc level5"><a href="bnaqq.html#bnaqw">Invoke Application Phase</a></p>
<p class="toc level5"><a href="bnaqq.html#bnaqx">Render Response Phase</a></p>
<p class="toc level3 tocsp"><a href="bnaqy.html">Further Information about JavaServer Faces Technology</a></p>
<p class="toc level2 tocsp"><a href="bnaqz.html">11.&nbsp;&nbsp;Using JavaServer Faces Technology in JSP Pages</a></p>
<p class="toc level2"><a href="bnatx.html">12.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnavg.html">13.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnawo.html">14.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="bnaxu.html">15.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">16.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="bnazf.html">17.&nbsp;&nbsp;Binding between XML Schema and Java Classes</a></p>
<p class="toc level2"><a href="bnbdv.html">18.&nbsp;&nbsp;Streaming API for XML</a></p>
<p class="toc level2"><a href="bnbhf.html">19.&nbsp;&nbsp;SOAP with Attachments API for Java</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbls.html">20.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbnb.html">21.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="bnboc.html">22.&nbsp;&nbsp;Session Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">23.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;V&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">24.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="bnbrl.html">25.&nbsp;&nbsp;Persistence in the Web Tier</a></p>
<p class="toc level2"><a href="bnbrs.html">26.&nbsp;&nbsp;Persistence in the EJB Tier</a></p>
<p class="toc level2"><a href="bnbtg.html">27.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level1 tocsp"><a href="bnbwi.html">Part&nbsp;VI&nbsp;Services</a></p>
<p class="toc level2"><a href="bnbwj.html">28.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bnbyk.html">29.&nbsp;&nbsp;Securing Java EE Applications</a></p>
<p class="toc level2"><a href="bncas.html">30.&nbsp;&nbsp;Securing Web Applications</a></p>
<p class="toc level2"><a href="bncdq.html">31.&nbsp;&nbsp;The Java Message Service API</a></p>
<p class="toc level2"><a href="bncgv.html">32.&nbsp;&nbsp;Java EE Examples Using the JMS API</a></p>
<p class="toc level2"><a href="bncih.html">33.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">34.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncjx.html">35.&nbsp;&nbsp;Connector Architecture</a></p>
<p class="toc level1 tocsp"><a href="bnckn.html">Part&nbsp;VII&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="bncko.html">36.&nbsp;&nbsp;The Coffee Break Application</a></p>
<p class="toc level2"><a href="bnclz.html">37.&nbsp;&nbsp;The Duke's Bank Application</a></p>
<p class="toc level1 tocsp"><a href="gexbq.html">Part&nbsp;VIII&nbsp;Appendixes</a></p>
<p class="toc level2"><a href="bncno.html">A.&nbsp;&nbsp;Java Encoding Schemes</a></p>
<p class="toc level2"><a href="bncnq.html">B.&nbsp;&nbsp;Preparation for Java EE Certification Exams</a></p>
<p class="toc level2"><a href="bncnt.html">C.&nbsp;&nbsp;About the Authors</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td width="705px">
         <div class="header">
             <div class="header-links-top">
                 <a href="http://java.sun.com">java.sun.com</a> |
                 <a href="http://docs.sun.com/">docs.sun.com</a><br>
             </div> 
             <img src="graphics/tutorialBanner.gif" width="704" height="120" alt="The Java&trade; EE 5 Tutorial"/>
             <div class="header-links">
	         <a href="index.html">Home</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/download.html">Download</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/JavaEETutorial.pdf">PDF</a> |
                 <a href="http://java.sun.com/javaee/5/docs/api/index.html">API</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/faq.html">FAQ</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/search.html">Search</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html">Feedback</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/history.html">History</a>
             </div>
             <div class="navigation">
                 <a href="bnapk.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
                 <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
                 <a href="bnaqd.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnapl"></a><h3>A Simple JavaServer Faces Application</h3>
<p>This section describes the general steps involved in developing a simple JavaServer Faces
application from the perspective of different development roles. These roles are:</p>
<ul><li><p>Page author, who creates pages by using the JavaServer Faces tag libraries.</p></li>
<li><p>Application developer, who programs custom converters, validators, listeners, and backing beans.</p></li>
<li><p>Component author, who creates custom UI components and renderers.</p></li>
<li><p>Application architect, who configures the application, including defining the navigation rules, configuring custom objects, and creating deployment descriptors.</p></li></ul>
<p>This application is quite simple, and so it does not include any
custom components. See chapter <a href="bnavb.html#bnavf">Writing a Method to Handle a Value-Change Event</a> to learn about the responsibilities of a component writer.</p>

<a name="bnapm"></a><h4>Steps in the Development Process</h4>
<p>Developing a simple JavaServer Faces application usually requires these tasks:</p>
<ul><li><p>Mapping the <tt>FacesServlet</tt> instance.</p></li>
<li><p>Creating the pages using the UI component and core tags.</p></li>
<li><p><a name="indexterm-661"></a><a name="indexterm-662"></a>Defining page navigation in the application configuration resource file.</p></li>
<li><p>Developing the backing beans.</p></li>
<li><p>Adding managed bean declarations to the application configuration resource file.</p></li></ul>
<p><a name="indexterm-663"></a>The example used in this section is the <tt>guessNumber</tt> application, located in the
<tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/web/</tt> directory. It asks you to guess a number between 0 and 10,
inclusive. The second page tells you whether you guessed correctly. The example also
checks the validity of your input. The system log prints Duke&rsquo;s number. <a href="#bnapn">Figure&nbsp;10-2</a>
shows what the first page looks like.</p><a name="bnapn"></a><h6>Figure&nbsp;10-2 The <tt>greeting.jsp</tt> Page of the <tt>guessNumber</tt> Application</h6><img src="figures/jsfIntro-guessNumber.gif" alt="Screen capture of Duke asking you to guess a number between 1 and 10, with a text field and a Submit button." width="505" height="218"></img><p>The source for the <tt>guessNumber</tt> application is located in the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/web/guessNumber/</tt> directory created when
you unzip the tutorial bundle (see <a href="gfiud.html">Chapter&nbsp;2, Using the Tutorial Examples</a>).</p><p>To build, package, deploy, and run this example using NetBeans IDE, follow these
steps:</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to:</p><pre><i>tut-install</i>/javaeetutorial5/examples/web/</pre></li>
<li><p>Select the <tt>guessNumber</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>In the Projects tab, right-click the <tt>guessNumber</tt> project, and select Undeploy and Deploy.</p></li>
<li><p>To run the application, open the URL <tt>http://localhost:8080/guessNumber</tt> in a browser.</p></li></ol>
<p>To build, package, and deploy this example using Ant, follow these steps:</p>
<ol><li><p>Go to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/web/guessNumber/</tt>.</p></li>
<li><p>Type <tt><b>ant</b></tt>.</p></li>
<li><p>Start the Application Server.</p></li>
<li><p>Type <tt><b>ant deploy</b></tt>.</p></li>
<li><p>To run the application, open the URL <tt>http://localhost:8080/guessNumber</tt> in a browser.</p></li></ol>
<p>To learn how to configure the example, refer to the deployment descriptor (the
<tt>web.xml</tt> file), which includes the following configurations:</p>
<ul><li><p>A <tt>display-name</tt> element that specifies the name that tools use to identify the application.</p></li>
<li><p>A <tt>servlet</tt> element that identifies the <tt>FacesServlet</tt> instance.</p></li>
<li><p>A <tt>servlet-mapping</tt> element that maps <tt>FacesServlet</tt> to a URL pattern.</p></li></ul>


<a name="bnapo"></a><h4>Mapping the <tt>FacesServlet</tt> Instance</h4>
<p>All JavaServer Faces applications must include a mapping to the <tt>FacesServlet</tt> instance
in their deployment descriptors. The <tt>FacesServlet</tt> instance accepts incoming requests, passes them to
the life cycle for processing, and initializes resources. The following piece of the
<tt>guessNumber</tt> example&rsquo;s deployment descriptor performs the mapping to the <tt>FacesServlet</tt> instance:</p><pre>&lt;servlet>
    &lt;display-name>FacesServlet&lt;/display-name>
    &lt;servlet-name>FacesServlet&lt;/servlet-name>
    &lt;servlet-class>javax.faces.webapp.FacesServlet
    &lt;/servlet-class>
    &lt;load-on-startup>1&lt;/load-on-startup>
&lt;/servlet>
&lt;servlet-mapping>
    &lt;servlet-name>FacesServlet&lt;/servlet-name>
    &lt;url-pattern>/guess/*&lt;/url-pattern>
&lt;/servlet-mapping></pre><p>The mapping to <tt>FacesServlet</tt> shown above uses a prefix mapping to identify a
JSP page as having JavaServer Faces components. Because of this, the URL to
the first JSP page of the application must include the mapping. To accomplish
this, the <tt>guessNumber</tt> example includes an HTML page that has the URL to
the first JSP page:</p><pre>&lt;a href="guess/greeting.jsp"></pre><p>See <a href="bnaxj.html#bnaxl">Identifying the Servlet for Life Cycle Processing</a> for more information on how to map the <tt>FacesServlet</tt> instance.</p>

<a name="bnapp"></a><h4>Creating the Pages</h4>
<p>Creating the pages is the page author&rsquo;s responsibility. This task involves laying out
UI components on the pages, mapping the components to beans, and adding tags
that register converters, validators, or listeners onto the components.</p><p>In this section you will build the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/examples/web/guessNumber/web/greeting.jsp</tt> page, the first page
of the <tt>guessNumber</tt> application. As with any JSP page, you&rsquo;ll need to add
the usual HTML and HEAD tags to the page:</p><pre>&lt;HTML xmlns="http://www.w3.org/1999/xhtml"xml:lang="en">
    &lt;HEAD> &lt;title>Hello&lt;/title> &lt;/HEAD>    
    ...
&lt;/HTML></pre><p>You&rsquo;ll also need a page directive that specifies the content type:</p><pre>&lt;%@ page contentType="application/xhtml+xml" %></pre>

<a name="bnapq"></a><h5>Declaring the Tag Libraries</h5>
<p>In order to use JavaServer Faces components in JSP pages, you need
to give your pages access to the two standard tag libraries, the HTML
component tag library and the core tag library using <tt>taglib</tt> declarations:</p><pre>&lt;%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
&lt;%@ taglib uri="http:.//java.sun.com/jsf/core" prefix="f" %></pre><p>The first taglib declaration declares the HTML component tag library with a prefix,
<tt>h</tt>. All component tags in the page have this prefix. The core tag
library is declared with the prefix <tt>f</tt>. All core tags in the page
have this prefix.</p><p><a href="bnaqd.html">User Interface Component Model</a> includes a table that lists all the component tags included with JavaServer
Faces technology. <a href="bnarf.html">Adding UI Components to a Page Using the HTML Component Tags</a> discusses the tags in more detail.</p>

<a name="bnapr"></a><h5>Adding the <tt>view</tt> and <tt>form</tt> Tags</h5>
<p>All JavaServer Faces pages are represented by a tree of components, called a
<b>view</b>. The <tt>view</tt> tag represents the root of the view. All JavaServer Faces
component tags must be inside of a <tt>view</tt> tag, which is defined in
the core tag library.</p><p>The <tt>form</tt> tag represents an input form component, which allows the user to
input some data and submit it to the server, usually by clicking a
button. All UI component tags that represent editable components (such as text fields
and menus) must be nested inside the <tt>form</tt> tag. In the case of
the <tt>greeting.jsp</tt> page, some of the tags contained in the form are <tt>outputText</tt>,
<tt>inputText</tt>, <tt>commandButton</tt>, and <tt>message</tt>. You can specify an ID for the form tag.
This ID maps to the associated form UI component on the server.</p><p>With the <tt>view</tt> and <tt>form</tt> tags added, our page looks like this (minus
the HTML and HEAD tags):</p><pre>&lt;%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
&lt;%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
&lt;f:view>
    &lt;h:form id="helloForm1">
    &lt;/h:form>
&lt;/f:view></pre>

<a name="bnaps"></a><h5>Adding a Label Component</h5>
<p>The <tt>outputText</tt> tag represents a label. The <tt>greeting.jsp</tt> page has two <tt>outputText</tt>
tags. One of the tags displays the number 0. The other tag displays
the number 10:</p><pre>    &lt;h:outputText lang="en_US"
         value="#{UserNumberBean.minimum}"/>
    &lt;h:outputText value="#{UserNumberBean.maximum}"/></pre><p>The <tt>value</tt> attributes of the tags get the values from the <tt>minimum</tt> and
<tt>maximum</tt> properties of <tt>UserNumberBean</tt> using <a name="indexterm-664"></a>value expressions, which are used to reference data
stored in other objects, such as beans. See <a href="bnaqm.html">Backing Beans</a> for more information
on value expressions.</p><p>With the addition of the <tt>outputText</tt> tags (along with some static text), the
greeting page looks like the following:</p><pre>&lt;%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
&lt;%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
&lt;f:view>
    &lt;h:form id="helloForm1">
        &lt;h2>Hi. My name is Duke. I&rsquo;m thinking of a number from
         &lt;h:outputText lang="en_US"
             value="#{UserNumberBean.minimum}"/> to
         &lt;h:outputText value="#{UserNumberBean.maximum}"/>.
        Can you guess it?&lt;/h2>
    &lt;/h:form>
&lt;/f:view></pre>

<a name="bnapt"></a><h5>Adding an Image</h5>
<p>To display images on a page, you use the <tt>graphicImage</tt> tag. The <tt>url</tt>
attribute of the tag specifies the path to the image file. Let&rsquo;s add
Duke to the page using a <tt>graphicImage</tt> tag:</p><pre>&lt;%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
&lt;%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
&lt;f:view>
    &lt;h:form id="helloForm1">
        &lt;h2>Hi. My name is Duke. I&rsquo;m thinking of a number from
         &lt;h:outputText lang="en_US"
             value="#{UserNumberBean.minimum}"/> to
         &lt;h:outputText value="#{UserNumberBean.maximum}"/>.
        Can you guess it?&lt;/h2>
        &lt;h:graphicImage id="waveImg" url="/wave.med.gif" />
    &lt;/h:form>
&lt;/f:view></pre>

<a name="bnapu"></a><h5>Adding a Text Field</h5>
<p><a name="indexterm-665"></a>The <tt>inputText</tt> tag represents a text field component. In the <tt>guessNumber</tt> example,
this text field takes an integer input value. The instance of this tag
included in <tt>greeting.jsp</tt> has three attributes: <tt>id</tt>, <tt>label</tt>, and <tt>value</tt>.</p><pre>&lt;h:inputText id="userNo" label="User Number"
        value="#{UserNumberBean.userNumber}">
        ...
&lt;/h:inputText></pre><p>The <tt>id</tt> attribute corresponds to the ID of the component object represented by
this tag. In this case, an <tt>id</tt> attribute is required because the <tt>message</tt>
tag (which is used to display validation error messages) needs it to refer
to the <tt>userNo</tt> component.</p><p>The <tt>label</tt> attribute specifies the name to be used by error messages to
refer to the component. In this example, label is set to <tt>User Number</tt>. As
an example, if a user were to enter 23, the error message that
would be displayed is:</p><pre>User Number: Validation Error: Value is greater than allowable maximum of 10.</pre><p><a name="indexterm-666"></a><a name="indexterm-667"></a>The <tt>value</tt> attribute binds the <tt>userNo</tt> component value to the bean property <tt>UserNumberBean.userNumber</tt>,
which holds the data entered into the text field.</p><p>After adding the <tt>inputText</tt> tag, the greeting page looks like the following:</p><pre>&lt;%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
&lt;%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
&lt;f:view>
    &lt;h:form id="helloForm1">
        &lt;h2>Hi. My name is Duke. I&rsquo;m thinking of a number from
         &lt;h:outputText lang="en_US"
             value="#{UserNumberBean.minimum}"/> to
         &lt;h:outputText value="#{UserNumberBean.maximum}"/>.
        Can you guess it?&lt;/h2>
        &lt;h:graphicImage id="waveImg" url="/wave.med.gif" />
        &lt;h:inputText id="userNo" label="User Number"
            value="#{UserNumberBean.userNumber}">
            ...
        &lt;/h:inputText>
    &lt;/h:form>
&lt;/f:view></pre><p>See <a href="bnaqm.html">Backing Beans</a> for more information on creating beans, binding to bean properties, referencing
bean methods, and configuring beans.</p><p>See <a href="bnarf.html#bnaro">Using Text Components</a> for more information on the <tt>inputText</tt> tag.</p>

<a name="bnapv"></a><h5>Registering a Validator on a Text Field</h5>
<p>By nesting the <tt>validateLongRange</tt> tag within a text field&rsquo;s component&rsquo;s tag, the page
author registers a <tt>LongRangeValidator</tt> onto the text field. This validator checks whether
the component&rsquo;s local data is within a certain range, defined by the <tt>validateLongRange</tt>
tag&rsquo;s <tt>minimum</tt> and <tt>maximum</tt> attributes.</p><p>In the case of the greeting page, you need to validate the
number the user enters into the text field. So, you add a <tt>validateLongRange</tt>
tag inside the <tt>inputText</tt> tag. The <tt>maximum</tt> and <tt>minimum</tt> attributes of the <tt>validateLongRange</tt>
tag get their values from the <tt>minimum</tt> and <tt>maximum</tt> properties of <tt>UserNumberBean</tt> using the
value expressions <tt>#{UserNumberBean.minimum}</tt> and <tt>#{UserNumberBean.maximum}</tt>. See <a href="bnaqm.html">Backing Beans</a> for details on value expressions.</p><p>After adding the <tt>validateLongRange</tt> tag, the page looks like this:</p><pre>&lt;%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
&lt;%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
&lt;f:view>
    &lt;h:form id="helloForm1">
        &lt;h2>Hi. My name is Duke. I&rsquo;m thinking of a number from
         &lt;h:outputText lang="en_US"
             value="#{UserNumberBean.minimum}"/> to
         &lt;h:outputText value="#{UserNumberBean.maximum}"/>.
        Can you guess it?&lt;/h2>
        &lt;h:graphicImage id="waveImg" url="/wave.med.gif" />
        &lt;h:inputText id="userNo" label="User Number"
            value="#{UserNumberBean.userNumber}">
                &lt;f:validateLongRange
                     minimum="#{UserNumberBean.minimum}"
                     maximum="#{UserNumberBean.maximum}" />
        &lt;/h:inputText>
    &lt;/h:form>
&lt;/f:view></pre><p>For more information on the standard validators included with JavaServer Faces technology, see
<a href="bnatc.html">Using the Standard Validators</a>.</p>

<a name="bnapw"></a><h5>Adding a Custom Message</h5>
<p>JavaServer Faces technology provides standard error messages that display on the page when
conversion or validation fails. In some cases, you might need to override the
standard message. For example, if a user were to enter a letter into
the text field on <tt>greeting.jsp</tt>, he or she would see the following error
message:</p><pre>User Number: &rsquo;m&rsquo; must be a number between -2147483648 and 2147483647 Example: 9346</pre><p>This is wrong because the field really only accepts values from 0
through 10.</p><p>To override this message, you add a <tt>converterMessage</tt> attribute on the <tt>inputText</tt> tag.
This attribute references the custom error message:</p><pre>&lt;h:inputText id="userNo" label="User Number"
         value="#{UserNumberBean.userNumber}"
         <b>converterMessage="#{ErrMsg.userNoConvert}"</b>>
...
&lt;/h:inputText></pre><p>The expression that <tt>converterMessage</tt> uses references the <tt>userNoConvert</tt> key of the <tt>ErrMsg</tt> resource bundle.
The application architect needs to define the message in the resource bundle and
configure the resource bundle. See <a href="#bnaqa">Configuring Error Messages</a> for more information on this.</p><p>See <a href="bnasp.html#bnass">Referencing Error Messages</a> for more information on referencing error messages.</p>

<a name="bnapx"></a><h5>Adding a Button</h5>
<p><a name="indexterm-668"></a><a name="indexterm-669"></a><a name="indexterm-670"></a><a name="indexterm-671"></a><a name="indexterm-672"></a>The <tt>commandButton</tt> tag represents the button used to submit the data entered in
the text field. The <tt>action</tt> attribute specifies an outcome that helps the
navigation mechanism decide which page to open next. <a href="#bnapz">Defining Page Navigation</a> discusses this further.</p><p>With the addition of the <tt>commandButton</tt> tag, the greeting page looks like the
following:</p><pre>&lt;%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
&lt;%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
&lt;f:view>
    &lt;h:form id="helloForm1">
        &lt;h2>Hi. My name is Duke. I&rsquo;m thinking of a number from
         &lt;h:outputText lang="en_US"
             value="#{UserNumberBean.minimum}"/> to
         &lt;h:outputText value="#{UserNumberBean.maximum}"/>.
        Can you guess it?&lt;/h2>
        &lt;h:graphicImage id="waveImg" url="/wave.med.gif" />
        &lt;h:inputText id="userNo" label="User Number"
            value="#{UserNumberBean.userNumber}">
                &lt;f:validateLongRange
                     minimum="#{UserNumberBean.minimum}"
                     maximum="#{UserNumberBean.maximum}" />
        &lt;/h:inputText>
        &lt;h:commandButton id="submit"
             action="success" value="Submit" />
    &lt;/h:form>
&lt;/f:view></pre><p>See <a href="bnarf.html#bnarw">Using Command Components for Performing Actions and Navigation</a> for more information on the <tt>commandButton</tt> tag.</p>

<a name="bnapy"></a><h5>Displaying Error Messages</h5>
<p><a name="indexterm-673"></a><a name="indexterm-674"></a>A <tt>message</tt> tag is used to display error messages on a page when
data conversion or validation fails after the user submits the form. The <tt>message</tt>
tag in <tt>greeting.jsp</tt> displays an error message if the data entered in
the field does not comply with the rules specified by the <tt>LongRangeValidator</tt> implementation, whose
tag is registered on the text field component.</p><p>The error message displays wherever you place the <tt>message</tt> tag on the page.
The <tt>message</tt> tag&rsquo;s <tt>style</tt> attribute allows you to specify the formatting style for
the message text. Its <tt>for</tt> attribute refers to the component whose value
failed validation, in this case the <tt>userNo</tt> component represented by the <tt>inputText</tt> tag
in the <tt>greeting.jsp</tt> page.</p><p>Put the <tt>message</tt> tag near the end of the page:</p><pre>&lt;%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
&lt;%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
&lt;f:view>
    &lt;h:form id="helloForm1">
        &lt;h2>Hi. My name is Duke. I&rsquo;m thinking of a number from
         &lt;h:outputText lang="en_US"
             value="#{UserNumberBean.minimum}"/> to
         &lt;h:outputText value="#{UserNumberBean.maximum}"/>.
        Can you guess it?&lt;/h2>
        &lt;h:graphicImage id="waveImg" url="/wave.med.gif" />
        &lt;h:inputText id="userNo" label="User Number"
            value="#{UserNumberBean.userNumber}"
            converterMessage="#{ErrMsg.userNoConvert}">
            &lt;f:validateLongRange
                     minimum="#{UserNumberBean.minimum}"
                     maximum="#{UserNumberBean.maximum}" />
        &lt;/h:inputText>
        &lt;h:commandButton id="submit"
             action="success" value="Submit" />
        &lt;h:message showSummary="true" showDetail="false"
                style="color: red;
                 font-family: &rsquo;New Century Schoolbook&rsquo;, serif;
                 font-style: oblique;
                 text-decoration: overline"
                 id="errors1"
                 for="userNo"/>
    &lt;/h:form>
&lt;/f:view></pre><p>Now you have completed the greeting page. Assuming you have also done the
<tt>response.jsp</tt> page, you can move on to defining the page navigation rules.</p>

<a name="bnapz"></a><h4>Defining Page Navigation</h4>
<p><a name="indexterm-675"></a><a name="indexterm-676"></a><a name="indexterm-677"></a>Defining page navigation involves determining which page to go to after the user
clicks a button or a hyperlink. Navigation for the application is defined in
the application configuration resource file using a powerful rule-based system. Here is one
of the navigation rules defined for the <tt>guessNumber</tt> example:</p><pre>&lt;navigation-rule>
    &lt;from-view-id>/greeting.jsp&lt;/from-view-id>
    &lt;navigation-case>
        &lt;from-outcome>success&lt;/from-outcome>
        &lt;to-view-id>/response.jsp&lt;/to-view-id>
    &lt;/navigation-case>
&lt;/navigation-rule>
&lt;navigation-rule>
    &lt;from-view-id>/response.jsp&lt;/from-view-id>
    &lt;navigation-case>
        &lt;from-outcome>success&lt;/from-outcome>
        &lt;to-view-id>/greeting.jsp&lt;/to-view-id>
    &lt;/navigation-case>
&lt;/navigation-rule></pre><p>This navigation rule states that when the button on the greeting page is
clicked the application will navigate to <tt>response.jsp</tt> if the navigation system is given
a logical outcome of <tt>success</tt>.</p><p>In the case of the Guess Number example, the logical outcome is
defined by the <tt>action</tt> attribute of the <tt>UICommand</tt> component that submits the form:</p><pre>&lt;h:commandButton id="submit" action="success"
     value="Submit" /></pre><p>To learn more about how navigation works, see <a href="bnaql.html">Navigation Model</a>.</p>

<a name="bnaqa"></a><h4>Configuring Error Messages</h4>
<p>In case the standard error messages don&rsquo;t meet your needs, you can create
new ones in resource bundles and configure the resource bundles in your application
configuration resource file. The <tt>guessNumber</tt> example has one custom converter message, as described
in <a href="#bnapw">Adding a Custom Message</a>.</p><p>This message is stored in the resource bundle, <tt>ApplicationMessages.properties</tt>:</p><pre>userNoConvert=The value you entered is not a number.</pre><p>The resource bundle is configured in the application configuration file:</p><pre>&lt;application>
    &lt;resource-bundle>
        &lt;base-name>guessNumber.ApplicationMessages&lt;/base-name>
        &lt;var>ErrMsg&lt;/var>
    &lt;/resource-bundle>
&lt;/application></pre><p>The <tt>base-name</tt> element indicates the fully-qualified name of the resource bundle. The <tt>var</tt>
element indicates the name by which page authors refer to the resource bundle
with the expression language. Here is the <tt>inputText</tt> tag again:</p><pre>&lt;h:inputText id="userNo" label="User Number"
    value="#{UserNumberBean.userNumber}"
        converterMessage="#{ErrMsg.userNoConvert}">
        ...
&lt;/h:inputText></pre><p>The expression on the <tt>converterMessage</tt> attribute references the <tt>userNoConvert</tt> key of the <tt>ErrMsg</tt>
resource bundle.</p><p>See <a href="bnaxb.html">Registering Custom Error Messages</a> for more information on configuring custom error messages.</p>

<a name="bnaqb"></a><h4>Developing the Beans</h4>
<p><a name="indexterm-678"></a>Developing beans is one responsibility of the application developer. A typical JavaServer Faces
application couples a backing bean with each page in the application. The backing
bean defines properties and methods that are associated with the UI components used
on the page.</p><p><a name="indexterm-679"></a><a name="indexterm-680"></a>The page author binds a component&rsquo;s value to a bean property using the
component tag&rsquo;s <tt>value</tt> attribute to refer to the property. Recall that the
<tt>userNo</tt> component on the <tt>greeting.jsp</tt> page references the <tt>userNumber</tt> property of <tt>UserNumberBean</tt>:</p><pre>&lt;h:inputText id="userNo" label="User Number"
            value="#{UserNumberBean.userNumber}">
...
&lt;/h:inputText></pre><p>Here is the <tt>userNumber</tt> backing bean property that maps to the data for
the <tt>userNo</tt> component:</p><pre>Integer userNumber = null;
...
public void setUserNumber(Integer user_number) {
    userNumber = user_number;
 }
public Integer getUserNumber() {
    return userNumber;
}
public String getResponse() {
    if(userNumber != null &amp;&amp;
         userNumber.compareTo(randomInt) == 0) {
            return "Yay! You got it!";
    } else {
        return "Sorry, "+userNumber+" is incorrect.";
    }
}</pre><p>See <a href="bnaqm.html">Backing Beans</a> for more information on creating backing beans.</p>

<a name="bnaqc"></a><h4>Adding Managed Bean Declarations</h4>
<a name="indexterm-681"></a><p>After developing the backing beans to be used in the application, you need
to configure them in the application configuration resource file so that the JavaServer
Faces implementation can automatically create new instances of the beans whenever they are
needed.</p><p><a name="indexterm-682"></a><a name="indexterm-683"></a>The task of adding managed bean declarations to the application configuration resource file
is the application architect&rsquo;s responsibility. Here is a managed bean declaration for <tt>UserNumberBean</tt>:</p><pre>&lt;managed-bean>
    &lt;managed-bean-name>UserNumberBean&lt;/managed-bean-name>
    &lt;managed-bean-class>
        guessNumber.UserNumberBean
    &lt;/managed-bean-class>
    &lt;managed-bean-scope>session&lt;/managed-bean-scope>
    &lt;managed-property>
        &lt;property-name>minimum&lt;/property-name>
        &lt;property-class>long&lt;/property-class>
        &lt;value>0&lt;/value>
    &lt;/managed-property>
    &lt;managed-property>
        &lt;property-name>maximum&lt;/property-name>
        &lt;property-class>long&lt;/property-class>
        &lt;value>10&lt;/value>
    &lt;/managed-property>
&lt;/managed-bean></pre><p>This declaration configures <tt>UserNumberBean</tt> so that its <tt>minimum</tt> property is initialized to 0,
its <tt>maximum</tt> property is initialized to 10, and it is added to
session scope when it is created.</p><p>A page author can use the unified EL to access one of
the bean&rsquo;s properties, like this:</p><pre>&lt;h:outputText value="#{UserNumberBean.minimum}"/></pre><p>For more information on configuring beans, see <a href="bnaqm.html#bnaqo">Configuring a Bean</a>.</p>
         </div>
         <div class="navigation">
             <a href="bnapk.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
             <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
             <a href="bnaqd.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
         </div>

         <div class="copyright">
      	    <p>The material in The Java&trade; EE 5 Tutorial is <a href='docinfo.html'>copyright</a>-protected and may not be published in other works without express written permission from Sun Microsystems.</p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

